A5.u.elementposition Method
Syntax
Arguments
- elementelementstringarray
A pointer to a DOM element or the ID of the element to position. An array of two elements or IDs can be passed in. In this case the first element is the element to position, and the second element is a child element of the positioned element that the positioning should be preformed relative to.
- locationstringarray
The relative location(s) to position the element to. See the description for a detailed list.
- targetelementstringobjectnull
A pointer to a DOM element or the ID of an element to use as the target area for the positioning. An object can be passed in to allow for programmatic positioning. If the element is being positioned relative to the container, then a null value can be passed in.
- xnumber
The "x" coordinate of the target area if the target is programmatic.
- ynumber
The "y" coordinate of the target area if the target is programmatic.
- widthnumber
The "width" of the target area if the target is programmatic.
- heightnumber
The "height" of the target area if the target is programmatic.
- settingsobject
The positioning settings.
- adjuststring
How to adjust the position of the element if the requested position would be outside of the visible area of the parent container. A value of "none" (the default) will not allow adjustments to the position of the element. A value of "both" will allow adjustments along both axes. A value of "major" will allow for adjustments along the major axis only. A value of "minor" will allow for adjustments along the minor axis only. A value of "x" or "y" will allow for adjustments on either the "x" or "y" axis only.
- offsetobject
Offsets to the position.
- majornumber
The "major" offset. See the description for more on the "major" and "minor" axes.
- minornumber
The "minor" offset. See the description for more on the "major" and "minor" axes.
- topnumber
The offset to add to the top of the element.
- leftnumber
The offset to add to the left of the element.
- rightnumber
The offset to add to the right of the element.
- bottomnumber
The offset to add to the bottom of the element.
- sizeobject
Size the element width and height.
- widthstring
Set the width of the element using CSS units as well as the custom "cw", "ch", "tw" and "th" units (container width/height and target width/height). The default value of "auto" can be used to keep the current width. Can be an expression, for instance "2tw+20px" would be two times the target width plus 20 pixels.
- heightstring
Set the height of the element using CSS units as well as the custom "cw", "ch", "tw" and "th" units (container width/height and target width/height). The default value of "auto" can be used to keep the current height. Can be an expression, for instance "2tw+20px" would be two times the target height plus 20 pixels.
- stretchstring
Which axes to automatically stretch. Values can be "none" (the default), "width", "height", "both", "major" or "minor". The values "major" and "minor" will stretch either the width or height depending on the location. See the description for more on the "major" and "minor" axes.
- dataobject
Information about the elements position.
- elementobject
Element specific information.
- xnumber
The "x" coordinate of the element in pixels.
- ynumber
The "y" coordinate of the element in pixels.
- topnumberboolean
The "top" position of the element in pixels. If the elements "top" has not been set then a value of "false" is returned.
- leftnumberboolean
The "left" position of the element in pixels. If the elements "left" has not been set then a value of "false" is returned.
- rightnumberboolean
The "right" position of the element in pixels. If the elements "right" has not been set then a value of "false" is returned.
- bottomnumberboolean
The "bottom" position of the element in pixels. If the elements "bottom" has not been set then a value of "false" is returned.
- widthnumber
The "width" of the element in pixels.
- heightnumber
The "height" of the element in pixels.
- compassobject
The best calculated direction from the element to the target. If the target is not part of the location used for positioning, then the compass will point to the container.
- primarystring
The primary direction of the compass. Values can be "top", "left", "right", "bottom" and "none".
- secondarystring
The secondary direction of the compass. Values can be "top", "left", "right", "bottom" and "none".
- offsetnumber
The offset from the along the primary direction relative to the "top" (for a primary direction of "left" or "right") or "left" (for "top" or "bottom") of the element
- xnumber
The "x" coordinate of the target area.
- ynumber
The "y" coordinate of the target area.
- topnumberboolean
The "top" position of the target area in pixels.
- leftnumberboolean
The "left" position of the target area in pixels.
- rightnumberboolean
The "right" position of the target area in pixels.
- bottomnumberboolean
The "bottom" position of the target area in pixels.
- widthnumber
The "width" of the target area.
- heightnumber
The "height" of the target area.
- transformstring
The transform CSS generated based off the transform setting. This can be used to perform animations using the A5.u.element.transition method.
Description
Position an element relative to a target or its container.
Discussion
The A5.u.element.position method can be used to position an element inside a container relative to the container, another element or specific location. A child of the element can be used as the positioning "target" be passing in an array of the element to position followed by the child element. This can be used to position a group of elements relative to an individual child of that group.
A "location" is passed in to specify where the element is to be positioned. This can be a string of a named position (which can use "," to separate multiple values, and "/" to automatically generate values), or an array of positions. If multiple positions are passed in, then the first position to be unobscured will be used. If all positions are partially obscured, then the least obscured position will be used.
A "location" is specified by a combination of one of ten vertical and ten horizontal position separated by a space character. Vertical positions are "container-above", "container-top", "target-above", "target-top", "container-center", "target-center", "target-bottom", "target-below", "container-bottom" and "container-below". Horizontal positions are "container-before", "container-left", "target-before", "target-left", "container-center", "target-center", "target-right", "target-after", "container-right" and "container-after". The four values: "above", "before", "after" and "below" are located outside the given context (e.g. the "container" or "target"). The five values: "top", "left", "center", "right" and "bottom" are located inside the given context. The vertical position is always placed before the horizontal. For example, to position the element as a left justified dropdown of the target the "location" would be "target-below target-left".
Shorthand can be used to create locations as well. When this technique is used, the context (e.g. the "container" or "target") is omitted, and a container position is indicated by using upper-case and a target position by lower-case. For example, to position an element on the top edge of the container, centered over the target, the value would be "TOP center" (the longhand for this being "container-top target-center").
If one of the positions is "center", and the other position is in the same context, then the "center" position may be omitted. For example, to position an element as a center justified dropdown of the target, the location can be "target-below" instead of "target-below target-center".
If the desired position of an element was as a left justified dropdown of the target that would be located above or below the target depending on available space, the values would be "target-below target-left" and "target-above target-left". This can be shortened using a "/" to "target-below/above target-left". It may be further shortened to "below/above left". The "/" shorthand can also be used multiple times. For example, "target-below/above target-left/right" would result in four locations (e.g. below or above the target and justified to the left or the right)
Example
// assume "id" is the ID of DIV that wants to be positioned